*ATTENTION* this is a preview version of mzscript 0.9, for the most part this
readme has NOT been updated. If you decide to test this module, please read
the changelog below very carefully. If you find any bugs (there should be a few)
or have any questions, please email ilmcuts@gmx.net. Thank you for your patience,
I hope you enjoy this update :)


============================ mzscript 0.9 beta ============================
               An advanced script module for LiteStep/PureLS
                       by Marcus Westerlund (maze)
                 updated by Karl-Henrik Henriksson (qwilk)
                      revised by Phil Stopford of leaf
                          also updated by ilmcuts
===========================================================================

First, the usual disclamer:
Use at your own risk (shouldn't be any trouble though)

===========================================================================
History:
===========================================================================

 mzscript 0.9 beta (2002-04-23) / ilmcuts
	- bugfix: vars weren't expanded in the !varSet & !varDump parameter lists
	- bugfix: varsaving was case sensitive
	- if a file can't be found the invalid filename will be shown
	- *mzScriptFile and *mzVarFile now work in scriptfiles too
	- !varDump spacing fixed; now appends to file instead of inserting at the top
	- added !bang parameters
		- %{args} is the complete parameter list
		- %{\1}, %{\2} etc. contain the parameters separately ("tokenized")
		- escape code %= added, it acts as " in the parameter list
	- !varShow improved.
	- varsaving function rewritten. reduced overhead and made it less buggy.
	- !varDump also rewritten. File doesn't have to exist any more.
	- !scriptload works again, %{vars} are expanded.
	- !varSave works again, %{vars} are expanded.
	- mzAutosaveVars accepts two values, "delayed" and "immediately"
		- if "delayed" is specified vars are saved on !refresh/!recycle/!quit
		- if "immediately" is specified the vars are saved the moment they are changed
	- restored PureLS compatibility thanks to TucknDar
	- many misc bugfixes

 mzscript 0.9 preview (2002-04-12) / ilmcuts
	- many internal changes (e.g. new, faster parser) [thanks Smoogle!]
	- vars are now defined in separate files (*mzVarFile)
	- multiple script files allowed (*mzScriptFile)
	- added mzScriptUseStep, this will also use step.rc as a scriptfile like mzscript did in 0.8
		- vars defined with *script var (old syntax possible ;)) won't be saved
		- step.rc will be processed last
	- vars added at runtime cannot be saved (mzAutosaveVars & !varSaveAll syntax changed)
	- script *start items are now executed last
		- mzNoStartOnRefresh will disable the *start items on !refresh
	- %{} is now the default syntax
		- use mzScriptOldSyntax to work with %[].
	- added !varDump. this will save all known vars to a given file.
	- misc minor changes
	- disabled in the preview: !varSave, !varReplace, !scriptload
	- readme still incomplete but should cover major changes

 mzscript 0.8.7 (2002-04-04) / ilmcuts (unreleased)
	- added internal var bpp - this returns the current bpp (32 bit, 16 bit...)

 mzscript 0.8.6l (2002-03-12) / Phil@leaf
    - mzScript now internally supports two forms of encapsulators.
	- Default and traditional is to use %[].
        - Specifying mzScriptNewSyntax will activate the replacement %{} encapsulators.

 mzscript 0.8.5l (2002-03-07) / Phil@leaf
    - mzScript now internally rounds floats up or down as required.
	- Done before addition/multiplication so be careful! (e.g. 4.2 + 4.5 becomes 4 + 5)
    - Added a !VarInt function to force any variable to become integer.

 mzscript 0.8l (2001-10-23) / Phil@leaf
    - Project settings changed to produce a multithreaded DLL.
	  - Size of compiled DLL has been halved with this change.
	- Compiled against most recent CVS of LiteStep 0.24.6.

 version 0.8 (2001-09-24) / qwilk
	- Now works with PureLS! (thanks to jugg)
	- Added !Refresh support
	- Added !Pause (courtesy of Maduin's pause.dll)
	- Made changes to make mzscript compile with current LSAPI
	- Cleaned up the source code

 version 0.7.2 (2000-05-22) / maze
	- Added internal vars mousex and mousey
	- Fixed case sensitivity, is now not case sensitive (should fix new build problem)

 version 0.7 (2000-05-19) / maze
	- Added !scriptload 
	- Added !scriptremove
	- Added !varMul
	- Added !setlistsep
	- Added internal variables to return system properties

 version 0.6 (2000-03-07) / maze
	- Added !varAdd
	- Added support for saving variables
	- Added !ifEval
	- Added more syntax on if bangs
	- Added support for custom rc-file
	- Added list functionality
	- Added var substitution
	- Added goto,gotoif and label to script
	- Added some minor things

 version 0.5 (2000-02-24) / maze
	- First version out


===========================================================================
Installation:
===========================================================================

----- How to load the module:

LoadModule c:\path_to_dll\mzscript.dll

----- However, using e-variables is highly recommended:

ThemeDir $LitestepDir$themes\MyTheme\
LoadModule "$ThemeDir$modules\mzscript\mzscript.dll" [threaded]

(please note that the e-variable LiteStepDir is defined automatically by LiteStep!)

[this parameter is optional, but may result in a performance increase - caution is advised though.]

===========================================================================
Usage:
===========================================================================

----- step.rc -----

*mzScriptFile filename
- Read script definitions from filename. Multiple scriptfiles possible. Files may include ; comments.

*mzVarFile filename
- Read %{vars} from filename. Multiples also possible. Files may include ; comments.

mzScriptUseStep
- step.rc and all included files are treated as scriptfiles. these files will be processed after
  all *mzScriptFile lines are processed.

mzBangChar |
- What char to use instead of ! for bang commands. This is useful
  for nesting bangs. (defaults to |)

mzListSeparator :
- Char to separate parts of variables when they are used as lists (defaults to : )

mzAutosaveVars delayed/immediately
- Automatically saves variables to the file they were read in from. "delayed" means
  variables are saved on !recycle/!refresh/!quit. "immediately" means variables are
  saved the instant they are changed via !varSet. (disabled by default)

mzScriptOldSyntax
- Use old %[var] syntax instead of the default %{var}

mzNoStartOnRefresh
- Doesn't execute the *script start lines on !refresh.

----- bangs -----

----- Variable manipulation bangs:

!varSet name The string 
or !varSet name "The string"
- Sets variable "name" to "The string"

!varRemove name
- Removes variable "name"

!varShow name
- Show context of "name"

!varRun name
- executes the contents of variable "name", can be a bang or a command

!varAdd name number
- Adds number to variable "name". A non valid number vill be the same as 0

!varMul name number
- Multiplies number with "name". A non valid number vill be the same as 0.
 Number may be float but "name" is always integer.

!varInt name
- Forces mzScript to convert the variable "name" to an integer value. Use on strings is 
untested and not recommended.

!varSave name	*disabled*
- Saves the variable "name" to the script file.

!varReplace name	*disabled*
- Saves the variable "name" to the script file, but only if it already exists.

!varSaveAll
- Saves all variables to the files they were defined in.

!varDump file
- Mainly for debugging purposes. Writes all vars, their values, and the files they were read
  in from to "file". Vardump will be appended to the file.

----- If bangs...

!ifExist name [command]
!ifNExist name [command] 
- Executes [command] if variable exists (or not).

!ifEq name "string" [command]
!ifNEq name "string" [command]
- Executes [command] if variable is equal (or not) to string.

!ifEval ("hello" <= "wow") [command]
- Evaluates expression (quite useful with var substitutions)
 Valid comparisons are:
 "<" less than
 "<=" less or equal to
 ">" greater than
 "=>" greater or equal to
 "=" equal to
 "<>" not equal to

where [command] may be of the following syntaxes:
    command arg
    'command arg'
    'command arg' else '|bang'
    '|bang hello' '"c:\foo bar\command" world'
    {command arg}
    {command arg} else {bang arg}

The first string between the ' signs is executed if true, if false the second (if it exists).
Likewise, the first string between { and } is executed (a must with nested ifs) if true,
if false the second string (if it exists).

----- Other bangs...

!msgbox msg
- Displays msg in a message box.

!exec command
- Executes command, may be a bang or a program (useful when invoked from someware else,
 var substitution takes place)

!setlistsep s
- Sets list separator character to s

!scriptload filename	*disabled*
- Loads script definition file from filename

!scriptremove bang_name_without_!
- Removes scriptbang bang_name_without_!

!pause [n]
- Pauses for n milliseconds (courtesy of Maduin's pause.dll)


----- scriptfile.rc -----

*Script start command
- Executes command on startup

*Script bang !thebang
- Start of a bangscript that will connected to !thebang

*Script exec command
- Part of a bangscript that executes command when the bang is invoked

*Script exit
- Exits a bangscript

*Script label labelname
- Used with goto and gotoif

*Script goto labelname
- Jumps to label labelname in bangscript. If this label is not found then the script is aborted.

*Script gotoif ("string1" <> "string2") labelname
- Jumps to label labelname in script if evaluation of expression is true. If the label is not
found then the bangscript is aborted. See !ifEval for valid comparisons.

*Script ~bang
- Declares the end of a bangscript.

----- scriptfile.rc -----

name string
- Sets variable name to "string".

Example for a varfile:

tasks shown
vwm hidden

This varfile defines two variables, %{tasks} with the value "shown" and %{vwm} with the value
"hidden".
HINT: if you use Litestep's "include" to also "include" your varfile, mzScript's %{vars} will
be $vars$ at the same time, although the $vars$ values aren't updated when the %{vars} values
change. This is planned for the final 0.9.

----- Substitutions -----

(This feature was implemented in version 0.6)
Substitutions are made in bangs and in scripts.
If mzScriptOldSyntax is set %[var] is used instead of %{}

%{var}
- is substituted with the contents of variable var. 

%{var:}
- is substituted with the first part of variable var's contents
 (before the first list separator).

%{var:_}
- is substituted with the second part of variable var's contents
 (starting from the first list separator).

?{"Questions" "subst on yes" "subst on no"}
- Pops up a message box with the message "Questions". If yes is clicked
 it is substituted with "subst on yes", if no is clicked it is substituted
 with "subst on no".

##### Examples:

Let's say variable hello is set to "c:\hi.txt:world.txt",
and that the separator is set to the default value of ":"

- notepad %{hello}
would execute as "notepad c:\hi.txt:world.txt"
- notepad %{hello:}
would execute as "notepad c"
- notepad %{hello:_}
would execute as "notepad \hi.txt:world.txt"


----- Internal variables -----

The internal variables are:

xresolution
yresolution
bpp
year
month
day
weekday
hour
minute
second
mousex
mousey

It should be quite obvious what they stand for. They are used as regular vars.

##### Example:

!msgbox %{hour}:%{minute}:%{second}

will show the current time in a message box.

Remember not to alter internal variables. It is possible, but you have to recycle 
to get them to act as functions again.

===========================================================================
Examples:
===========================================================================

----- Simple -----

##### varfile:

vwm shown
bar shown

##### scripfile:

*Script start notepad

;First bangscript
*Script bang !togglebar
*Script exec !ifeq bar "shown" '|varset bar hidden' else '|varset bar shown'
*Script exec !toggleslider [1]
*Script exec !ToggleShortcutGroup 1
*Script exec !ToggleCommand 
*Script exec !SystrayToggle 
*Script exec !ifeq vwm "shown" |VWMRollup
*Script ~bang

;Second bangscript
*Script bang !togglevwm
*Script exec !ifeq vwm "shown" '|varset vwm hidden' else '|varset vwm shown'
*Script exec !ifeq bar "hidden" |varset vwm shown
*Script exec !ifneq bar "hidden" |VWMRollup
*Script exec !ifeq bar "hidden" |togglebar
*Script ~bang


----- Advanced -----

##### scriptfile:

;Not to be changed by varsave ... using start and !varset instead of var
;Contains turing program, makes three ones and terminates on two states
*Script start !varset t_program "one:one::1:r:two:two::1:l:one:one:1:1:l:one:two:1:1::exit"

;Bang used by turing to shift tape
*Script bang !turing_left
*Script exec !varset t_left "%[t_right:]:%[t_left]"
*Script exec !varset t_right "%[t_right:_]"
*Script ~bang

;Bang used by turing to shift tape
*Script bang !turing_right
*Script exec !varset t_right "%[t_left:]:%[t_right]"
*Script exec !varset t_left "%[t_left:_]"
*Script ~bang

;A turing bang. Using t_program as turing program
*Script bang !turing
*Script exec !varset t_left ""
*Script exec !varset t_right ""
*Script exec !varset state "%[t_program:]"
*Script label start
*Script exec !varset prog "%[t_program:_]"
*Script label loop
*Script gotoif ("%[prog:]" <> "%[state]") skipp
*Script exec !varset tmp %[prog:_]
*Script gotoif ("%[tmp:]" <> "%[t_right:]") skipp
*Script exec !varset tmp %[tmp:_]
*Script exec !varset t_right "%[tmp:]:%[t_right:_]"
*Script exec !varset tmp %[tmp:_]
*Script exec !ifeval ("%[tmp:]" = "r") |turing_right
*Script exec !ifeval ("%[tmp:]" = "l") |turing_left
*Script exec !varset tmp %[tmp:_]
*Script exec !varset state %[tmp:]
*Script goto start
*Script label skipp
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script gotoif ("%[prog]" <> "") loop
*Script exec !varremove tmp
*Script label loop2
*Script exec !turing_right 
*Script gotoif ("%[t_left]" <> "") loop2
*Script exec !msgbox Result - %[t_right]
*Script ~bang


(...and this short example shows that there is no limitations to
what can be done with this script according to A. Turing)

===========================================================================
Some things:
===========================================================================
version 0.5 (maze)
I hope this will be of some use, I know it has been for me (that's why I wrote it).
I don't know if there will be more versions to come (is there demand?), but eventually
I may add sending keystrokes to windows. (Suggestions?)

version 0.6 (maze)
Oh well. I did make some additions. But now I will probably leave this module alone for
a while. But you are welcome to send me your suggestions and bug reports.

version 0.7 (maze)
Not much to say. I'm thinking of doing plugin support, but I dont know what that would be 
good for. I may check out the case sensitivity problem some day.

version 0.8 (qwilk)
Well, what can I say? I am just proud to be part of the mzscript legacy! <vbg>
I hope you enjoy it, especially the users of PureLS who has been without this
awesome module for too long...

version 0.8.5 (phil@leaf)
I'm glad to be able to contribute the rounding up/down and float to integer conversion. 
For as long as I can remember, this module has been powering LDE and it's great to be able 
to give something back.

===========================================================================
Contact (authors in order of appearance):
===========================================================================

Marcus Westerlund (maze)
marcus@cs.umu.se
http://www.acc.umu.se/~macce

Karl-Henrik Henriksson (qwilk)
qwilk@desktopian.org
http://desktopian.org/
